ggtree: an r package for visualization and annotation of phylogenetic trees with their covariates and other associated data

The ggtree package

The ggtree package is designed for annotating phylogenetic trees with their associated data of different types and from various sources. These data could come from users or analysis programs and might include evolutionary rates, ancestral sequences, etc., that are associated with the taxa from real samples, or with the internal nodes representing hypothetic ancestor strain/species, or with the tree branches indicating evolutionary time courses. For instance, the data could be the geographic positions of the sampled avian influenza viruses (informed by the survey locations) and the ancestral nodes (by phylogeographic inference) in the viral gene tree (Lam et al. 2012).

ggtree supports the graphical language of ggplot2, with which high level of customization can be intuitive and flexible. However, ggplot2 itself does not provide low-level geometric objects or other support for tree-like structures. Even though outbreaktools and phyloseq are developed based on ggplot2, the most valuable part of ggplot2 syntax – adding layers of annotations – is not supported in these packages. For example, if we have plotted a tree without taxa labels, outbreaktools and phyloseq provide no easy way for general r users, who have little knowledge about the infrastructures of these packages, to add a layer of taxa labels.

ggtree extends ggplot2 to support tree objects and implements a geometric layer, geom_tree, to support visualizing tree structure. In ggtree, viewing a phylogenetic tree is relatively easy, via the command ‘ggplot(tree_object) + geom_tree() + theme_tree()’ or ‘ggtree(tree_object)’ for short. Layers of annotations can be added one by one via the ‘+’ operator. To facilitate tree visualization, ggtree provides several geometric layers, including geom_treescale for adding legend of tree scale (genetic distance, divergence time, etc.), geom_range for displaying uncertainty of branch lengths (confidence interval or range, etc.), geom_tiplab for adding taxa label, geom_tippoint and geom_nodepoint for adding symbols of tips and internal nodes, geom_hilight for highlighting a clade with rectangle and geom_cladelabel for annotating a selected clade with a bar and text label (Table 2).

File formats and S4 classes

In ggtree, the S4 class defines a compound tree-based object that contains the tree and other information associated to the tree, branches or nodes. ggtree can read a number of tree file formats, including newick and nexus (via ape), NHX, jplace (Matsen et al. 2012) and phylip, into a S4 tree object. Non-standard analysis output files from various evolutionary biology software packages including beast (Bouckaert et al. 2014), epa (Berger, Krompass & Stamatakis 2011), hyphy (Pond, Frost & Muse 2005), paml (Yang 2007), phylodog (Bastien et al. 2013), pplacer (Matsen, Kodner & Armbrust 2010), raxml (Stamatakis 2014), revbayes (Sebastian et al. 2014) and r8s (Sanderson 2003) (Table 1) can also be parsed into S4 objects using functions read.beast, read.codeml_mlc, read.codeml, read.hyphy, read.jplace, read.nhx, read.paml_rst, read.phylip, read.raxml and read.r8s (Fig. 1, Table 2). After parsing, some node/branch-specific attribute data (e.g. evolutionary rates, ancestral/taxon sequences) are extracted from the files and stored in the S4 tree object. An overview of S4 classes and corresponding parser functions is illustrated in Fig. 1.

Furthermore, ggtree provides a function, merge_tree, to combine two trees together with their node/branch-specific attribute data. Essentially, as a result, one such attribute (e.g. evolutionary rate) can be mapped to another attribute (e.g. d_N/d_S) of the same branch/node for comparison and further computations (Fig. 2). ggtree can also directly visualize and annotate phylo, multiphylo, phylo4, phylo4d, obkdata and phyloseq tree-related objects that are defined in other r packages. The tree object in ggtree can also be converted, via get.tree(), to phylo or multiphylo objects that are widely used in other r packages. In addition, ggtree provides fortify method to convert the tree object to a tidy data frame, which is familiar to r users and easy to manipulate. Therefore, ggtree represents an infrastructure that enables phylogeny/taxon-related data inferred from different external computer programs or r packages, to be unified and analysed in r.

Example 1: parsing tree and analysis output files

To illustrate the utilities of ggtree, we used a previously published data set: 76 H3 hemagglutinin gene sequences of a lineage containing swine and human influenza A viruses (Liang et al. 2014). The data set was re-analysed by beast for timescale estimation and codeml for synonymous and non-synonymous substitutions estimation. In this example, we first parsed the outputs from beast using read.beast and from codeml using read.codeml into two tree objects. Then, the two objects containing two sets of branch/node-specific data were merged via the merge_tree function.

After merging the beast_tree and codeml_tree objects, all branch/node-specific data inferred by beast and codeml are available in the merged_tree object, in the components [1-13] and [14-25] of the vector above. We further converted the tree object to data frame, df, and visualized hexbin scatter plot of d_N/d_S, d_N and d_S inferred by codeml vs. rate inferred by beast on the same branches.

The output is illustrated in Fig. 2. We can then test the association of these branch/node-specific data using Pearson correlation, which in this case showed that d_N and d_S are significantly associated with rate but not d_N/d_S.

Example 2: phylogenetic tree visualization and annotation

The following example turns the merged_tree into a graphic object with tree branches coloured by branch-specific substitution rates (rate) as shown in Fig. 3a.

Other branch/node-specific data stored in the tree object (Fig. 5) can be displayed as an additional graphic layer of annotation on top of a tree. Complex presentations of trees are made possible by adding multiple layers of annotations. Phylogenetic tree can be rescaled using any numerical variable associated with branches. For instance, branch-specific estimates of d_N, d_S and ω from codeml analysis, can be used as lengths and colours of the branches in the tree (Fig. 3b). Tree nodes can be given different symbols based on the categorical values associated (Fig. 3c). ggtree can display a tree in different layouts, including rectangular, slanted, circular and fan layouts for phylogram and cladogram, rooted/unrooted, timescaled and two-dimensional phylogenies.

Compared to other phylogenetic tree visualizing packages, ggtree excels at visual exploration of tree structure and related data. For example, complex tree view with several annotation layers can be transferred to a new tree object without step-by-step re-creation. We have created an operator, %<%, to update a tree view with a new tree object. The following example rescales the branch lengths of the tree (merged_tree) with the branch-specific d_N values and updates the graphic object (p) with this new tree via %<%. The branch colours of this updated tree view were re-mapped from ‘rate’ to ‘dN’.

The groupClade function assigns the branches and nodes under different clades into different groups. Similarly, groupOTU function assigns branches and nodes to different groups based on user-specified groups of operational taxonomic units (OTUs) that are not necessarily within a clade, but can be monophyletic (clade), polyphyletic or paraphyletic. A phylogenetic tree can be annotated by mapping different line type, size, colour or shape to the branches or nodes that have been assigned to different groups. In the following example (Fig. 3c), we assigned branches and nodes to different groups based on the host species of the taxa via groupOTU(). According to the groupings, branches were then given different colours and line types, and the taxa were given symbols with different colours and shapes. We also applied the timescale, in Gregorian calendar, to the branch lengths by setting the most recent sampling date (mrsd).

To facilitate viewing and manipulating a phylogenetic tree, ggtree provides a number of helper functions. For example, the gzoom or viewClade functions allow the user to zoom into a selected portion or display a selected clade respectively. Other common tree manipulations could be achieved by collapse, expand, rotate, flip, etc., functions. A list of the major ggtree functions is given in Table 2, and their detailed explanations and examples are provided in the online vignette.

Example 3: two-dimensional trees

The y-axis or width of a conventionally laid out tree (i.e. with tree branches spanning horizontally along the x-axis, as shown in Fig. 3) often provides only regular spatial separation to the tree branches, without quantitative biological meanings. ggtree can draw ‘two-dimensional’ trees by rescaling the y-axis/tree width to a node-specific numerical attribute that might be a measure of certain biological characteristics of the taxa and hypothetical ancestors in the tree. In this example, we used the previous timescaled tree object and aimed to scale its y-axis/tree width based on the predicted N-linked glycosylation sites (NLG) for each of the taxon and ancestral sequences. The NLG sites were predicted using the netnglyc 1.0 Server (Blom et al. 2004) and were read into r and stored in NAG variable (Appendix S2). To scale the y-axis, the parameter yscale in the ggtree() function is set to a numerical or categorical variable. If yscale is a categorical variable, users should specify how the categories are to be mapped to numerical values via the yscale_mapping variable as demonstrated in this case. The resultant two-dimensional tree is shown in Fig. 4.

Example 4: more complex tree annotations

In this example, we demonstrate more complex tree annotation with additional texts and shapes (Fig. 5). We first visualized the tree in timescale and branches coloured by d_N/d_S. The tree was annotated with clade probabilities and the amino acid substitutions. The substitutions were determined via parent–child sequence comparison from the taxon sequences and ancestral sequences that can be estimated by any of hyphy, baseml or codeml.

While ggtree supports tree annotation using data from a list of software (Table 1), it also easily accepts user-defined data. In ggtree, the operator %<+% has been defined to allow user-defined annotation data (host.df in this example) to attach to a tree graphic object. In this example, we attached the host species information to the tree view and coloured the circle symbols and labels of taxa based on this information.

Users may have a matrix of data (from experiments or data analysis) about the taxa in the phylogenetic tree. In ggtree, this data matrix can be displayed as a heat map aligning with the corresponding taxa at the right side of the tree by gheatmap function. Here, we annotated the tree with a heat map of the genotypes for each taxon (Fig. 5). In the genotype matrix, the colour of each of the eight boxes indicates the lineage of each gene segment of the viruses that was classified according to Lam et al. (2011) and Liang et al. (2014).

ggtree provides subview function to add a subplot in a new layer of main plot. In this example, the tree with the associated matrix was condensed into rectangular and fan shapes and was plotted as subplot inside Fig. 5.

In addition to heat map display of taxa-associated matrix data, the underlying multiple sequence alignment of the taxa could be displayed with the tree using the msaplot function. Furthermore, trees can also be annotated with subplots of different types of graphs (e.g. bar, pie, box plot) using inset function or with silhouette images taken from the PhyloPic data base (http://phylopic.org) with phylopic function.